Table of Contents
mig33 is an exciting new instant messaging client for cell phones. It was developed for South Africa by Project Goth Pty Ltd., a private Australian company established to deliver consumers with cheaper mobile communication alternatives using the internet. It now currently works in over 200 different countries and has thousands of registered users. More information is available here: mig33 website .
The purpose of this specification is to document the protocol so that alternative clients can be created for systems that can not run the original Java MIDlet. This document covers the version of the protocol that works with version 2.04 and higher of the mig33 Java MIDlet. It may or may not cover past versions. As of the last review date this document only covers the chat portion of mig33.
All communication using the mig33 protocol occurs between client and server. There is no peer to peer communication (at least not with the chat/instant message protocol).
Before any communication can occur between multiple clients, a client must login to the server. The login process takes place as a 3 way challenge - response system. The client first sends information about itself to the server, including its username. The server then sends a challenge asking the client to respond with a hashcode of the clients password concatenated with a randomly generated string from the server. If the client responds successfully, the login process suceeds and the client can officially start chatting.
After logging in the client will have the option of sending private messages, joining chat rooms, and interacting with groups of users as well as individual users. Like IRC channels, mig33 chat rooms offer the ability for users to kick other users. Unlike IRC, it takes a majority of votes to kick a user out of a chat room. Individual clients can be ignored and blocked. A client can also set its "visibility" to other clients.
The mig33 server can be reached by connecting to gateway.mig33.com. The server listens for mig33 data on ports 25, 80, and 9119. In the case of port 80, the mig33 protocol is "embedded" inside HTTP. It is recommended that mobile users avoid using port 80, due to the higher data usage.
Please note that throughout this document, all numbers are in hexadecimal unless stated otherwise. Integers consisting of more than one byte are stored with the most significant byte first, and the least significant byte last. This is often referred to big endian, network byte order. All text strings are preceded by a four byte long TEXT_LEN field, indicating the length of the string.
General structure of a mig33 TCP packet. All packets from both client and server use this structure:
Table 1. Packet structure
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 1 byte | 02 | MAGIC | Identifies the packet as a mig33 packet. |
| 2 bytes | xx xx | COMMAND1 | High two bytes part of the command code for type of packet. |
| 2 bytes | xx xx | COMMAND2 | Low two bytes part of the command code for type of packet. |
| 4 bytes | xx xx xx xx | PACK_LEN | The length of the payload after this point. |
| variable | PARAMS | Varable length data specific to a certain command. |
The PARAMS portion of the packet contains a list of block structures. The structure of each block is as follows:
Table 2. Block structure
| Length | Name | Description |
|---|---|---|
| 2 bytes | ID | The ID number of the block. |
| 4 bytes | LENGTH | The length of the block. |
| variable | CONTENT | The contents of the block. |
The following commands are available for the client to send to the server:
Table 3. Client commands
| High command bytes | Low command bytes | Name | Description |
|---|---|---|---|
| 00 02 (2) | xx xx | KEEP_ALIVE | The keep alive packet. |
| 00 64 (100) | 00 02 (2) | REGISTER | The registration packet |
| 00 C8 (200) | 00 01 (1) | LOGIN_1 | The initial login packet |
| 00 CA (202) | 00 02 (2) | LOGIN_RESP | Login response to challenge packet sent by server. |
| 01 90 (400) | 00 03 (3) | GET_CLIST | Get contact list. |
| 01 F4 (500) | 00 06 (6) | SEND_MSG | Send a message to an entity (chat room or contact) |
Not yet described in detail
Table 4. Undocumented client commands
| High command bytes | Low command bytes | Name | Description |
|---|---|---|---|
| 02 BC (700) | 00 04 (4) | Possibly related to list of chat rooms. | |
| 02 BF (703) | 00 05 (5) | Chat related. Join room? |
The following commands can be sent from the server to the client, either as a response to a client command, or to notify the client of some event.
Table 5. Server commands
| High command bytes | Low command bytes | Name | Description |
|---|---|---|---|
| 00 00 (0) | 00 00 (0) | ERROR_MESSAGE | A packet that notifies the client of an error. |
| 00 00 (0) | 00 01 (1) | LOGIN_NOTIFY | A packet that notifies the client that the server is down, or under going maintanence. |
| 00 00 (0) | 00 02 (2) | LOGIN_BAD_RESP | Login failure message when Client sends a bad LOGIN_RESP packet. |
| 00 01 (1) | 00 02 (2) | REGISTER_OK | The message that the server sends when registration (the REGISTER packet) is successful. |
| 00 03 (3) | xx xx | KEEP_ALIVE_RESP | The keep alive response packet. |
| 00 C9 (201) | 00 01 (1) | LOGIN_CHAL | Login challenge sent from server to client after receiving LOGIN_1 packet. |
| 00 CB (203) | 00 02 (2) | LOGIN_OK / MOTD | Login OK message with message of the day |
| 01 91 (401) | 00 03 (3) | CLIST_GROUPS | Packet sent with groups after requesting contact list. |
| 01 92 (402) | 00 03 (3) | CLIST_BUDDIES | Packet sent with buddies after requesting contact list. |
| 01 93 (403) | 00 03 (3) | CLIST_TERMINATOR | Packet sent to tell mig33 that the contact list is sent. |
| 01 94 (404) | 00 00 (0) | CLIST_STATUS_CHANGE | Packet sent to tell mig33 that the status of someone on your buddy list has changed. |
| 01 F4 (500) | 00 00 (0) | RECV_MSG | Receive a message from an entity. (Chatroom or contact) |
| 01 F6 (502) | 00 00 (0) | RECV_SYS_MSG | Receive a system message |
This section goes through the individual packets that the client can send.
The keep alive packet contains no data. The low command bytes contain the sequence number. This sequence number always seems to start at 4. A keep alive packet must be sent every 60 seconds. Each time it is sent the sequence number is increased by one.
A client must send this packet if they wish to register a new account with mig33.
Table 6. REGISTER contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 04 | MARK_CELL | Used to mark the beginning of a cellphone telephone number string. |
| 4 bytes | xx xx xx xx | CELLNUM_LEN | The length of a celular phone number (include country code) |
| variable | CELLNUM | The cellphone number without dashes or dots. Example 1-310-555-5554 would be "13105555554" | |
| 2 bytes | 00 03 | MARK_PASSWORD | Used to mark the beginning of a password string block. |
| 4 bytes | xx xx xx xx | PASSWORD_LEN | The length of the password you wish to use during registration. |
| variable | PASSWORD | The password | |
| 2 bytes | 00 02 | MARK_USERNAME | Used to mark the beginning of a username string block |
| 4 bytes | xx xx xx xx | USERNAME_LEN | The length of the username you are registering. |
| variable | USERNAME | The username you are registering. | |
| 2 bytes | 00 01 | X1 | Unknown. Ending marker? |
| 4 bytes | 00 00 00 01 | UNKNOWN_LEN | Unknown but always 00 00 00 01. |
| 1 byte | 01 | X5 | Unknown. Always 01. |
The initial packet sent to a server.
Table 7. LOGIN_1 contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 09 | X1 | Unknown marker. |
| 4 bytes | 00 00 00 04 | X2 | Unknown. |
| 4 bytes | 00 00 00 01 | X3 | Unknown. |
| 2 bytes | 00 08 | MARK_PLAT | The marker for the platform block of the packet |
| 4 bytes | xx xx xx xx | TEXT_LEN1 | The length of the J2ME platform string |
| variable | J2ME_PLAT | The J2ME platform. Some examples in the wild:
| |
| 2 bytes | 00 07 | MARK_VERSTRING | The marker for the mig33 version string. |
| 4 bytes | 00 00 00 09 | TEXT_LEN2 | 9 for the length of "J2MEv2.04" or "J2MEv3.00" or "J2MEv3.02". |
| 9 bytes | xx xx xx xx xx xx xx xx xx | MIDLET_VERSION | The bytes of the string "J2MEv2.04" or "J2MEv3.00" or "J2MEv3.02" |
| 2 bytes | 00 05 | MARK_USERNAME | The marker for the username string. |
| 4 bytes | xx xx xx xx | TEXT_LEN3 | the length of your username. |
| variable | USERNAME | the bytes of your username. | |
| 2 bytes | 00 03 | MARK_VERSION | Marker for the version number as a short. |
| 4 bytes | 00 00 00 02 | VERSION_NUM_LEN | The length of the version number. sizeof(uint16_t). |
| 2 bytes | xx xx | VERSION_NUM | The version number in a short. It should
be either:
|
| 2 bytes | 00 02 | X9 | Unknown. |
| 4 bytes | 00 00 00 01 | X10 | Unknown. |
| 1 byte | xx | X11 | 01 for version 204, 02 for version 300 and above. |
| 2 bytes | 00 01 | X12 | Unknown |
| 4 bytes | 00 00 00 02 | X13 | Unknown. |
| 2 bytes | 00 01 | X14 | Unknown |
The login response to challenge packet sent by server.
Table 8. LOGIN_RESP contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 01 | MARK_HASHCODE | A marker used to indicate that this block is for the hash code. |
| 4 bytes | 00 00 00 04 | HASHCODE_LEN | The length of the hash code |
| 4 bytes | xx xx xx xx | HASHCODE | The 4 byte calculated hash code of the server's HASH_STRING concatenated with the client's password. |
HASHCODE is calclated by taking the server's HASH_STRING, then concatenating it with the client's password (in all lowercase) and running it through a hash code function. The function is the same used from Java's String hashCode() method.
This packet is created to send a message to a mig33 entity (either a chat room or contact).
Table 9. SEND_MSG contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 08 | MARK_MSG | A marker to indicate that this block contains the message. |
| 4 bytes | xx xx xx xx | MSG_LEN | The length of the message you are going to send |
| variable | MSG | A string containing the message to send | |
| 2 bytes | 00 06 | X2 | Unknown. |
| 4 bytes | 00 00 00 02 | X3 | Unknown. |
| 2 bytes | 00 01 | X4 | Unknown. |
| 2 bytes | 00 04 | MARK_DESTINATION | A marker to indicate that this block contain the destination entity. |
| 4 bytes | xx xx xx xx | DESTINATION_LEN | The length of the destination's name |
| variable | DESTINATION | The name of the destination. Either a chat room or mig33 contact | |
| 2 bytes | 00 03 | X6 | Unknown |
| 4 bytes | 00 00 00 01 | X7 | Unknown |
| 1 byte | 03 | X8 | Unknown |
| 2 bytes | 00 02 | MARK_USER | A marker used to indicate that this block contains your username. |
| 4 bytes | xx xx xx xx | USER_NAME_LEN | The length of your user name. |
| variable | USER_NAME | Your user name | |
| 2 bytes | 00 01 | X10 | Unknown. |
| 4 bytes | 00 00 00 01 | X11 | Unknown. |
| 1 byte | 01 | X12 | Unknown. |
This section goes through the individual packets that the server can send.
The error message packet is sent back to the client to inform the client that an error has occurred.
Table 10. ERROR_MESSAGE contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 02 | MARK_ERROR | A marker to indicate that this block contains an error string. |
| 4 bytes | xx xx xx xx | ERROR_LEN | The length of the error string. |
| variable | ERROR_STRING | The error string. | |
| 2 bytes | 00 01 | MARK_UNKNOWN | Unknown. |
| 4 bytes | 00 00 00 02 | UNKNOWN_LEN | Unknown |
| 2 bytes | 00 01 | UNKNOWN | Unknown. |
Login notify message to inform client that server is experiencing difficulties.
Table 11. LOGIN_NOTIFY contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 02 | X1 | Unknown marker. |
| 4 bytes | xx xx xx xx | TEXT_LEN1 | The length of the notification string. |
| variable | NOTICE_STRING | The notification string |
Login failure message when Client sends a bad LOGIN_RESP packet.
Table 12. LOGIN_BAD_RESP contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 02 | X1 | Unknown. |
| 4 bytes | xx xx xx xx | TEXT_LEN1 | The length of the error string. |
| variable | ERROR_STRING | A string indicating the error. | |
| 2 bytes | 00 01 | X2 | Unknown. |
| 4 bytes | 00 00 00 02 | X3 | Unknown. |
| 2 bytes | 00 01 | X4 | Unknown. |
Registration successful message when client sends a proper REGISTER packet.
Table 13. REGISTER_OK contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 01 | X1 | Unknown. Possibly a marker for the welcome message. |
| 4 bytes | xx xx xx xx | WELCOMEMSG_LEN | The length of the welcome message |
| variable | WELCOMEMSG | The welcome message |
The KEEP_ALIVE_RESP packet is sent from the server to the client after the server receives a KEEP_ALIVE packet. This packet contains no data. A sequence number is stored in the low command bytes. It seems to always match the sequence number from the last KEEP_ALIVE packet.
The login challenge packet.
Table 14. LOGIN_CHAL contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 02 | X1 | Unknown. |
| 4 bytes | xx xx xx xx | TEXT_LEN1 | The length of an unknown string. |
| variable | X2 | An unknown random string. | |
| 2 bytes | 00 01 | X1 | Unknown. |
| 4 bytes | xx xx xx xx | TEXT_LEN2 | The length of the hashing string. |
| variable | HASH_STRING | The bytes of the hashing string. |
The HASH_STRING is used in the LOGIN_RESP packet sent by the client to generate a proper hash code.
The login OK message with optional message of the day.
Table 15. LOGIN_OK / MOTD contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 0C | BLOCK_EXCHANGE_RATE | Used to mark the exchange rate block. Not in all responses. |
| 4 bytes | xx xx xx xx | EXCHANGE_RATE_LEN | The length of the exchange rate message |
| variable | EXCHANGE_RATE | The exchange rate message | |
| 2 bytes | 00 0B | X2 | Unknown. |
| 4 bytes | xx xx xx xx | CURRENCY_LEN | Length of the currency field |
| variable | CURRENCY | The currency. "USD" for US dollars. | |
| 2 bytes | 00 0A | X3 | Unknown. |
| 4 bytes | xx xx xx xx | UNKNOWN_IP_LEN | An IPv4 address |
| variable | IP_ADDRESS | An ip address. (e.g. "202.154.106.233") | |
| 2 bytes | 00 09 | X4 | Unknown. |
| 4 bytes | 00 00 00 04 | X5 | Unknown. |
| 4 bytes | 00 00 00 03 | X6 | Unknown. |
| 2 bytes | 00 08 | X7 | Unknown. |
| 4 bytes | 00 00 00 01 | X8 | Unknown. |
| 1 byte | 00 | X9 | Unknown. |
| 2 bytes | 00 06 | X10 | Unknown. |
| 4 bytes | 00 00 00 01 | X11 | Unknown. |
| 1 byte | 00 | X12 | Unknown. |
| 2 bytes | 00 03 | X13 | Unknown. |
| 4 bytes | xx xx xx xx | MOTD_LEN | Length of the MOTD string |
| variable | MOTD | The message of the day | |
| 2 bytes | 00 02 | X14 | Unknown. |
| 4 bytes | 00 00 00 01 | X15 | Unknown. |
| 2 bytes | 00 | X16 | Unknown. |
| 1 byte | 00 01 | X17 | Unknown. |
| 4 bytes | xx xx xx xx | MOBILE_NUM_LEN | The length of the string containing your mobile number |
| variable | MOBILE_NUM | Your mobile number including country code without () or dashes |
The packet sent after the client requests the contact list. This packet contains the groups on the contact list. Each group is sent in a different packet.
Table 16. CLIST_GROUPS contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 02 | MARK_GROUPNAME | A marker that indicates this block contains the name of the group. |
| 4 bytes | xx xx xx xx | GROUPNAME_LEN | The length of the name of the group |
| variable | GROUPNAME | The name of the group. (e.g. "mig33 Contacts") | |
| 2 bytes | 00 01 | MARK_ID | A marker for an unknown block. |
| 4 bytes | 00 00 00 04 | ID_LEN | Seems to always be 4. |
| 4 bytes | xx xx xx xx | ID | An ID number for this group. |
The ID number is used when you get the buddies in the contact list. In block 4 of the contact packet, the ID code will tell you which group a buddy belongs to.
The packet sent after the client requests the contact list. This packet contains the buddies on the contact list. Each buddy is sent in a different packet.
Table 17. CLIST_BUDDIES contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 19 | MARK_UNKNOWN | A marker for an unknown block. |
| 4 bytes | 00 00 00 01 | UNKNOWN_LEN | The length for some unknown data. Possibly a flag. |
| 1 byte | 00 | UNKNOWN | An unknown piece of data. Seems to always be 0? |
| 2 bytes | 00 03 | MARK_USERNAME | A marker for the username |
| 4 bytes | xx xx xx xx | USERNAME_LEN | The length of the username |
| variable | USERNAME | The username. | |
| 2 bytes | 00 0D | MARK_STATUS | A marker used to indicate a buddy's status. |
| 4 bytes | 00 00 00 01 | STATUS_LEN | The length of the status byte. |
| 1 byte | xx | STATUS | Status. 0x63 = "Offline", 0x01 = "Online". |
| 2 bytes | 00 02 | MARK_GROUP_ID | A marker used to indicate which group a buddy is in. |
| 4 bytes | 00 00 00 04 | GROUP_ID_LEN | The length of the GROUP_ID. |
| 4 bytes | xx xx xx xx | GROUP_ID | The group ID that this buddy belongs to. |
| 2 bytes | 00 0C | MARK_BUDDY_NAME | A marker used ot indicate the buddies name again. |
| 4 bytes | xx xx xx xx | BUDDY_NAME_LEN | The length of the buddies name. |
| variable | BUDDY_NAME | The buddy's name. | |
| 2 bytes | 00 01 | MARK_BUDDY_ID | A marker for the buddy ID. |
| 4 bytes | 00 00 00 04 | BUDDY_ID_LEN | The length of the buddy ID. |
| 4 bytes | xx xx xx xx | BUDDY_ID | The Buddy ID. |
The packet sent to notify a client that a buddy's status has changed.
Table 18. CLIST_STATUS_CHANGE contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 02 | MARK_STATUS | A marker that indicates this block contains the status number. |
| 4 bytes | 00 00 00 01 | STATUS_LEN | The length of the status byte. |
| 1 byte | xx | STATUS | The users status. 0x63 = Offline, 0x01 = Online. |
| 2 bytes | 00 01 | MARK_BUDDY_ID | A marker to indicate the buddy id. |
| 4 bytes | 00 00 00 04 | BUDDY_ID_LEN | The length of the buddy ID. |
| 4 bytes | xx xx xx xx | BUDDY_ID | The buddy id who's status has changed. |
The packet sent to notify a client that another user sent a message to a chat room or mig33 contact.
Table 19. RECV_MSG contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 08 | MARK_MSG | A marker that indicates this block is the chat message. |
| 4 bytes | xx xx xx xx | MSG_LEN | Length of the chat message. |
| variable | MSG | The bytes that make up the chat message. | |
| 2 bytes | 00 06 | MARK_X1 | A marker for an unknown block. |
| 4 bytes | 00 00 00 02 | X2_LEN | An unknown length |
| 2 bytes | 00 01 | X3 | An unknown piece of data. |
| 2 bytes | 00 04 | MARK_DESTINATION | A marker for the destination string. |
| 4 bytes | xx xx xx xx | DESTINATION_LEN | Length of the string containing the destination. |
| variable | DESTINATION | The name of the destination. Can be either a chatroom or a user's name. | |
| 2 bytes | 00 03 | MARK_X4 | A marker for an unknown block. |
| 4 bytes | 00 00 00 01 | X5_LEN | An unknown length |
| 1 byte | xx | X6 | Unknown. Can be 03 or 01. This may be an indication of whether the message is to a chat room or to a user. |
| 2 bytes | 00 02 | MARK_USER | A marker for the user who sent the message. |
| 4 bytes | xx xx xx xx | USER_LEN | The lenght of the username |
| variable | USER | The username that sent the message. | |
| 2 bytes | 00 01 | MARK_X7 | An unknown marker. |
| 4 bytes | 00 00 00 01 | X8_LEN | An unknown length |
| 1 byte | 01 | X9 | Unknown. |
This packet is sent to the client when the server needs to inform the client about some event.
Table 20. RECV_SYS_MSG contents
| Length | Content (if fixed) | Name | Description |
|---|---|---|---|
| 2 bytes | 00 05 | MARK_DATA | A marker that indicates this block contains the data of the system message. |
| 4 bytes | xx xx xx xx | DATA_LEN | Length of the data message. |
| variable | DATA | The bytes that make up the data. Could be a URL. | |
| 2 bytes | 00 04 | MARK_DESC | A marker that indicates this block contains a description of the data in the system mesage. |
| 4 bytes | xx xx xx xx | DESC_LEN | Length of the description. |
| variable | DESC | The bytes that make up the decription. | |
| 2 bytes | 00 02 | MARK_INVOKER | A marker that indicates this block contains the invoker of the system message. |
| 4 bytes | xx xx xx xx | INVOKER_LEN | Length of the invoker's nick. |
| variable | INVOKER | The bytes that make up the invoker's name | |
| 2 bytes | 00 01 | MARK_UNKNOWN | An unknown block of data. |
| 4 bytes | 00 00 00 01 | UNKNOWN_LEN | An unknown length. Seems to always be 1 byte. |
| 1 byte | 01 | Unknown | Seems to always be 01. |
This document was generated on 2007-10-06-07:00 02:21:00-07:00 with DocBook XSL Stylesheets version 1.72.0.